package com.example.casserver.service;

import com.example.casserver.model.ServiceTicket;
import com.example.casserver.model.TicketGrantingTicket;

/**
 * CAS票据服务接口
 * 负责管理CAS票据的生命周期，包括生成、验证和失效
 * 是CAS单点登录系统的核心组件
 */
public interface TicketService {
    /**
     * 创建TGT票据
     * 当用户成功登录时调用，生成代表用户会话的TGT
     * 
     * @param username 用户名
     * @return 新创建的TGT
     */
    TicketGrantingTicket createTicketGrantingTicket(String username);

    /**
     * 获取TGT票据
     * 根据票据ID获取TGT对象，用于验证用户是否已登录
     * 
     * @param tgtId 票据ID
     * @return 如果票据有效则返回TGT对象，否则返回null
     */
    TicketGrantingTicket getTicketGrantingTicket(String tgtId);

    /**
     * 使TGT票据失效
     * 当用户登出时调用，清除用户的登录状态
     * 
     * @param tgtId 需要失效的TGT ID
     */
    void invalidateTicketGrantingTicket(String tgtId);

    /**
     * 使用TGT生成服务票据
     * 当用户访问客户端应用时调用，实现单点登录
     * 
     * @param tgtId TGT ID
     * @param service 目标服务地址
     * @return 新生成的ST
     */
    ServiceTicket generateServiceTicket(String tgtId, String service);

    /**
     * 为指定用户和服务生成新的服务票据（兼容旧接口）
     * 直接生成ST，不依赖TGT
     * 
     * @param username 用户名
     * @param service 目标服务地址
     * @return 新生成的服务票据
     */
    ServiceTicket generateTicket(String username, String service);

    /**
     * 验证服务票据的有效性
     * 当客户端应用提交ST进行验证时调用
     * 
     * @param ticketId 票据ID
     * @return 如果票据有效则返回票据对象，否则返回null
     */
    ServiceTicket validateTicket(String ticketId);

    /**
     * 使指定的票据失效
     * 当ST被成功验证后调用，防止重复使用
     * 
     * @param ticketId 需要失效的票据ID
     */
    void invalidateTicket(String ticketId);

    /**
     * 使指定用户的所有票据失效
     * 通常在用户登出时调用，清除所有相关票据
     * 
     * @param username 用户名
     */
    void invalidateUserTickets(String username);
} 